Mastering YAML Options in Quarto

Introduction

  • YAML defines the structure and settings of your Quarto documents.
  • YAML stands for “YAML Ain’t Markup Language”.
  • Correct YAML setup makes your documents professional and customizable.

What is YAML?

  • Located at the top of .qmd files.

  • Surrounded by triple dashes ---.

  • Controls:

    • Title, author, date

    • Output format

    • Table of contents

    • Fonts, themes

    • Citations, bibliography

    • Code execution

Basic YAML Example

---
title: "My Report"
author: "A Student"
date: "2025-04-28"
format: docx
editor: visual
---
  • Simple and clean.
  • Tells Quarto to create a Word document.

Metadata Options

Option Purpose
title: Title of document
subtitle: Subtitle
author: Author(s)
date: Date shown in output

Example:

title: "Annual Report"
author: "John Doe"
date: "April 2025"

Format Options

  • Simple:
format: docx
  • Complex (Multiple Formats):
format:
  html:
    toc: true
  pdf:
    toc: true
  docx:
    toc: true

Word-specific Options

format:
  docx:
    reference-doc: "custom-style.docx"
    toc: true
    toc-depth: 2
    number-sections: true
    keep-md: true
Option Purpose
reference-doc: Custom style Word file
toc: Table of contents
toc-depth: TOC levels
number-sections: Numbered headings

Code Execution Options

execute:
  echo: true
  eval: true
  warning: false
  error: false
  message: false
Option Purpose
echo: Show code?
eval: Evaluate code?
warning: Show warnings?
error: Show errors?
message: Show messages?

Appearance Options

theme: cosmo
mainfont: "Times New Roman"
fontsize: 12pt
geometry: margin=1in
  • theme: sets visual style (for HTML/Slides)
  • mainfont: customizes font
  • fontsize: sets size
  • geometry: sets margins

Table of Contents (TOC) Options

toc: true
toc-depth: 2
toc-title: "Contents"
toc-location: left
  • toc: add table of contents
  • toc-depth: depth of headings
  • toc-title: title name
  • toc-location: place TOC left, right, inline

Bibliography and Citations

bibliography: references.bib
csl: apa.csl
citeproc: true
  • bibliography: BibTeX file path
  • csl: Citation Style Language file
  • citeproc: Use citation processor

Full Example YAML

---
title: "Research Report"
subtitle: "Financial Analysis 2025"
author: "A Student"
date: today
format:
  docx:
    reference-doc: "template.docx"
    toc: true
    toc-depth: 2
    number-sections: true
execute:
  echo: true
  warning: false
theme: cosmo
mainfont: "Georgia"
fontsize: 11pt
geometry: margin=1in
bibliography: refs.bib
csl: apa.csl
editor: visual
---

Important Notes

✅ YAML is indentation-sensitive.

✅ Use spaces (not tabs).

✅ Check filenames carefully.

✅ Maintain consistent structure.

Summary Table

Block Purpose
title, author, date Metadata
format: Output type
execute: Code settings
theme, font, size Appearance
toc, number-sections Structure
bibliography, csl Citations

Practice Exercise ✍️

✅ Create a YAML that:

  • Title: “Student Report”

  • Author: “Your Name”

  • Date: today

  • Format: docx with TOC

  • Font: Times New Roman, fontsize 12pt

  • Theme: simple

References

Thank You 🙏

Happy Document Writing!